Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update standards based on Nov 2019 PyHC meeting discussion #16

Open
wants to merge 5 commits into
base: main
Choose a base branch
from

Conversation

namurphy
Copy link
Contributor

This pull request is to include changes to the community standards based on the discussion at the PyHC meeting from November 2019. We probably still need to update the author list to reflect the people who were in attendance in Boulder. We'll need to review this during a PyHC telecon before we accept this, which will probably be in January 2020.

Here are the notes from the meeting back in November:

  • Change: All functions, classes, and modules in the public-facing API...
  • Question: what do people think of Black?
    • It’s opinionated and consistent with the standards
  • Add actual links for “System[link]” and “acceptance[link]”
  • Python 2.7 has about a thousand hours left
  • Change: “clearly and constructively explain when a contribution is not accepted”
  • Change in add my name to standards #15: “Projects should have a reporting procedure for violations of the code of conduct (see [link to NumFOCUS’s for ).”
  • Add a bullet point
    • Be explicit on what versions of dependencies a package supports.
    • Strong recommendation that we should support NumPy Enhancement Proposal 29 which provides recommendations on which prior versions of Python and NumPy to support.
    • “Should” is fine
  • Do we want to figure out a way to “grade” packages on the PyHC website?
    • Making an assessment can be really useful to packages
    • Probably need someone(s) to go through packages
    • Goes back to governance
    • Self-assessments are a first step; and are important
      • Maybe have a template for that particular type of PR
    • Maybe if someone wants to add their project to PyHC’s website, then they should provide the results of their self-assessment
    • Astropy's affiliated packages list has a “traffic light system” (red/orange/green)
    • Would be wonderful to have community reviews; really helpful for packages
      • JOSS is a good model for this
    • Should current packages plan on going through this procedure, doing a self-assessment?
    • We’ll need to first figure out what the items to be evaluated on: what the metrics are
    • Does anyone want to volunteer?
      • Eerie silence
    • Bring up at next telecon
    • By the next meeting in the spring, aim to have all packages on the website reviewed

This still needs authors/contributors of the revision added, and to be
reviewed during one of our telecons.
We discussed the amendments from the fall 2019 meeting during a PyHC
telecon on 06-Jan-2020, and approved the changes.  We still need to
update the list of authors of the amendment.

One topic of discussion during this telecon was on adoption of NEP 29
(which created a community-wide standard for how long to support older
versions of Python and SciPy) by PyHC packages.  Stuart Mumford
suggested that it be okay for some packages to have stricter
standards, and that packages can support older versions of NumPy and
Python if they so choose.  Michael Hirsch brought up that
usage/download statistics from a package that supports Python 3.5+
showed that very few people are using Python 3.5 at the moment (and
also that Python 3.5 gives the most trouble for the testing matrix).
I brought up that core packages like SunPy should follow the
guidelines of NEP 29 most closely, while packages that are currently
under development and have few users would be okay in supporting
Python 3.7+ or even 3.8+ if the development phase is going to last
~1-2 years.  We decided that using "should" leaves open enough leeway
for us to accept packages that have different requirements.  I forgot
to mention that I think that we should follow the same guidelines for
Astropy (and ideally packages within PyHC) as we do for NumPy.

(These notes are a convolution of what people actually said, and my
ability to remember 42 minutes into the past.)
@namurphy namurphy marked this pull request as ready for review January 6, 2020 17:20
@namurphy
Copy link
Contributor Author

namurphy commented Jan 6, 2020

If you approve these changes and would like to be listed as a co-author, please let me know! You can add a comment, suggest a commit, or approve this pull request. It'd be helpful to know the name/affiliation you would like used if they're different from the original document, as well as your ORCID if you have one.

Many thanks to @ehsteve and everyone else who shepherded the process the first time around!

@namurphy
Copy link
Contributor Author

namurphy commented Jan 6, 2020

We also have been talking about who is willing to volunteer for going through PyHC packages and evaluating the extent to which each package meets the standards. We could potentially do this during the hackathon following our spring meeting in Cambridge. The main meeting will be from April 27-29, with the hackathon beginning on the afternoon of the 29th and lasting ~1-2 days.

@wtbarnes
Copy link
Contributor

wtbarnes commented Jan 6, 2020

My affiliation should be updated to NRL and my ORCID is 0000-0001-9642-6089.

@wtbarnes
Copy link
Contributor

wtbarnes commented Jan 6, 2020

We also have been talking about who is willing to volunteer for going through PyHC packages and evaluating the extent to which each package meets the standards. We could potentially do this during the hackathon following our spring meeting in Cambridge.

I wonder if this could be a responsibility of the proposed PyHC developer position? At least the first pass and then the initial review could be further evaluated by the community.

Copy link
Member

@ehsteve ehsteve left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry I did not participate in the phone discussion. I think it would always be better to have discussions of PRs on GitHub so that they are "in the record" and everyone is able to participate.

standards.md Outdated
@@ -29,12 +35,12 @@ Definitions:
5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended.
6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git).
7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle).
8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand this change. This suggests that non public-facing functions do not need doc strings. How is a contributor supposed to interact with developer code that is not documented?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm...good point. I've occasionally written short private helper functions/methods with no arguments that have their one-line docstring encoded in the function name, so the docstring doesn't end up adding any additional information. I'm also sometimes lax on docstrings for unstable temporary implementations that I know will not be lasting long. Perhaps we could say that all public facing functions/etc must have docstrings, and that private functions/etc should generally have docstrings?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "all public facing functions/etc must have docstrings, and that private functions/etc should generally have docstrings" is a good compromise. I know there are non-public facing functions in SciPy that use internal comments instead of docstrings when the functions are never supposed to be interacted with externally.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't believe docstrings and comments are always needed if the code is self-explanatory. If the function has a clear "verb" that explains by itself what's the intention then comments and documentation may, not only, be redundant but also it can make the project harder to maintain - as it may be forgotten and never updated even making the documentation misleading! (and that's worse than no documentation at all!!)
So, rather than force people to have docstrings I would prefer to encourage good practices when naming functions, variables, etc. (which we don't have anything on that respect and I believe it's as important, or more, than documentation in itself). Chapter 2 of Clean Code is a good text about why we should encourage it more.

In any case, I agree with @namurphy's must/should rewrite.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Certainly requiring full numpydoc docstrings on all private functions is overkill. +1 on @aburrell 's suggestion

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with going with the "should". I don't really like the idea of encouraging "second-class" functions that are more poorly documented than others but I understand the concern here. I do know that for sunpy there are many important non-public facing functions that need good documentation for developers to interact with them!

standards.md Outdated
8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System and acceptance testing are also recommended.
10. **Dependencies**: Projects should import the minimum number of packages necessary. Adding new dependencies should be a __considered__ decision.
11. **Python 3**: All packages must be compatible or work towards being compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 is January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would update this to state that Python 2 has reached its end of life and would rephrase to be more forceful in that all packages MUST support Python 3.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed completely! This slipped my mind because I was making these edits in 2019.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. python3 may be redundant with 12. deprecation. It may now (2020) finally be sufficient to just omit mention of python2 and just mention NEP29.

@namurphy
Copy link
Contributor Author

namurphy commented Jan 6, 2020

I think it would always be better to have discussions of PRs on GitHub so that they are "in the record" and everyone is able to participate.

Good point! I had thought I had emailed the list after I originally made the PR, but I forgot to... I put my notes from today's discussion in the commit log, though I should have put it as a comment here. For discussions at meetings/telecons, we should make sure that notes are posted in the corresponding PR.

One topic of discussion during this telecon was on adoption of NEP 29 (which created a community-wide standard for how long to support older versions of Python and SciPy) by PyHC packages. Stuart Mumford suggested that it be okay for some packages to have stricter standards, and that packages can support older versions of NumPy and Python if they so choose. Michael Hirsch brought up that usage/download statistics from a package that supports Python 3.5+ showed that very few people are using Python 3.5 at the moment (and also that Python 3.5 gives the most trouble for the testing matrix). I brought up that core packages like SunPy should follow the guidelines of NEP 29 most closely, while packages that are currently under development and have few users would be okay in supporting Python 3.7+ or even 3.8+ if the development phase is going to last ~1-2 years. We decided that using "should" leaves open enough leeway for us to accept packages that have different requirements. I forgot to mention that I think that we should follow the same guidelines for Astropy (and ideally packages within PyHC) as we do for NumPy.

(These notes are a convolution of what people actually said, and my ability to remember 42 minutes into the past.)

standards.md Outdated
@@ -29,12 +35,12 @@ Definitions:
5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended.
6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git).
7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle).
8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "all public facing functions/etc must have docstrings, and that private functions/etc should generally have docstrings" is a good compromise. I know there are non-public facing functions in SciPy that use internal comments instead of docstrings when the functions are never supposed to be interacted with externally.

Amended on 06-Jan-2020 by (in alphabetical order)

**N. Murphy** (CfA),

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A. G. Burrell (NRL). Also, A. Halford is now at NASA GSFC.

@scivision
Copy link

scivision commented Jan 6, 2020

minimum Python version observations

I have required Python 3.6 for over a year on almost 100% of my packages (aggregate millions of users across geoscience, life sciences, aerospace, etc) with only a handful of complaints, including from incorporation into Linux distributions, offline/proprietary/OEM users and others not captured by PyPi.

  • PyMap3D (230K total PyPi downloads) has < 1% Python 3.5 PyPi downloads. PyMap3D still supports Python 3.5 to support OEM with long dev cycle on embedded systems.
  • Numpy is down to about 15% Python 3.5 PyPi downloads, and that may start dropping soon as Python 3.5 won't be supported in the next Numpy release.

Although there are limitations on relevance of PyPi download stats (does not account for conda and apt install etc), this script allows easy plotting of last 6 months of PyPi download data over time: https://github.com/scivision/pypistats-plots

As Jeff also noted, there are increasing penalties to supporting Python 3.5. If one looks at and assumes sufficient representation of PyPi stats, Python 3.5 may be a small audience for a growing number of PyHC packages. In my opinion the main penalties of Python 3.5 include:

  • declining CI support
  • rapidly declining package support
  • lack of newer subprocess features beneficial to managing tricky external processes
  • lack of complete type annotation -- which helps catch bugs new and old
  • Python 3.6 f-strings help avoid print() mistakes

Python 3.7 brings dataclasses and better UTF8 locale support among other benefits

14. **Binaries**: Binary files should be added to the package repository only when necessary in order to keep packages as light as possible. Jupyter notebooks can be binary files and should not be committed to the package repository but can be provided in other repositories.
15. **Code of conduct**: Each project must adopt a code of conduct that is compatible with the [Contributor Covenant](https://www.contributor-covenant.org) and make it publicly available.

12. **Deprecation Policy** (in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)): Each project should support (1) all minor versions of Python released 42 months prior to the project, and at minimum the two latest minor versions; and (2) all minor versions of NumPy released in the 24 months prior to the project, and at minimum the last three minor versions. In ``setup.py``, the ``python_requires`` variable should be set to the minimum supported version of Python. All supported minor versions of Python should be in the test matrix and have binary artifacts built for the release. Minimum Python and NumPy version support should be adjusted upward only on major and minor releases, and never on a patch release.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...In setup.py or setup.cfg, the python_requires ...

Although perhaps too technical for the standards document, in my opinion setup.cfg should be used as much as possible to allow better tool introspection without needing to install. For security, best practices, etc.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @scivision. We should encourage to keep that metadata on setup.cfg or pyproject.toml.

@scivision
Copy link

scivision commented Jan 6, 2020

Re: Black, I think it may be too much to have in PyHC standards in general, I have run into its corner cases that make code less readable. Also the whole defaulting to double quotes thing is problematic to me, although black -S is a workaround to retain single quotes.

I would rather have a statement encouraging setup.cfg over setup.py if we're going to get technical :-)

@scivision
Copy link

re: Docs
in my opinion this should include as OK even those that use non-readthedocs sites like GitHub Pages. I don't recall the source, but I read several months ago that packages of mine that do use numpydoc extensively with GitHub Pages were marked as not having docs because I don't use readthedocs.

Copy link
Contributor

@dpshelio dpshelio left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good @namurphy! Thanks!!

Re Black: I'm with @scivision - I wouldn't like to enforce it anywhere. Most of the times I've used I've found myself unhappy afterwards. I don't think that having "perfect" style at costs of readability has any advantages. Instead of suggesting an automatic linter I would keep the suggestion as we have on 7.

Re "grading packages": I'm happy to offer volunteer to review systems and packages... but as my free time allows me to go through them. So slowly. Additionally to the points you've linked, there's also the Best practice badge which is a big form that it needs to be filled up. I could use such questionaire to review the different projects (like I did with SunPy a while ago).

My affiliation hasn't changed, and my ORCID is: 0000-0003-0784-6909

standards.md Outdated
@@ -29,12 +35,12 @@ Definitions:
5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended.
6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git).
7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle).
8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't believe docstrings and comments are always needed if the code is self-explanatory. If the function has a clear "verb" that explains by itself what's the intention then comments and documentation may, not only, be redundant but also it can make the project harder to maintain - as it may be forgotten and never updated even making the documentation misleading! (and that's worse than no documentation at all!!)
So, rather than force people to have docstrings I would prefer to encourage good practices when naming functions, variables, etc. (which we don't have anything on that respect and I believe it's as important, or more, than documentation in itself). Chapter 2 of Clean Code is a good text about why we should encourage it more.

In any case, I agree with @namurphy's must/should rewrite.

8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System and acceptance testing are also recommended.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe we should add links to all the four types of tests that are mentioned here. I've just found the software testing fundamentals website which describe them quite well. Otherwise, people that haven't obtained any software development training wouldn't really understand the differences.

14. **Binaries**: Binary files should be added to the package repository only when necessary in order to keep packages as light as possible. Jupyter notebooks can be binary files and should not be committed to the package repository but can be provided in other repositories.
15. **Code of conduct**: Each project must adopt a code of conduct that is compatible with the [Contributor Covenant](https://www.contributor-covenant.org) and make it publicly available.

12. **Deprecation Policy** (in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)): Each project should support (1) all minor versions of Python released 42 months prior to the project, and at minimum the two latest minor versions; and (2) all minor versions of NumPy released in the 24 months prior to the project, and at minimum the last three minor versions. In ``setup.py``, the ``python_requires`` variable should be set to the minimum supported version of Python. All supported minor versions of Python should be in the test matrix and have binary artifacts built for the release. Minimum Python and NumPy version support should be adjusted upward only on major and minor releases, and never on a patch release.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @scivision. We should encourage to keep that metadata on setup.cfg or pyproject.toml.

Copy link
Contributor

@jklenzing jklenzing left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. - J. Klenzing (NASA GSFC)

@blalterman
Copy link
Contributor

Please add me to the list. Orcid is 0000-0001-6673-3432

Copy link
Contributor

@jtniehof jtniehof left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also (maybe after this is approved) do a wrap of long lines so that the diff is a little easier to read? I know there will always be weirdness with that (rewrapping when something is longer or shorter) but this was hard...hopefully doing so would also provide enough context so that changing numbers (by inserting new guidelines) doesn't look like something completely new.

@@ -29,12 +35,12 @@ Definitions:
5. **License**: Projects must provide a license. Projects should use permissive licenses for open source scientific software (e.g., the BSD 2-clause, BSD 3-clause, or BSD+Patent licenses). Copyleft licenses such as GPL are not recommended and OSI-approved permissive licenses are recommended.
6. **Version control**: All code must use version control. It is strongly recommended that projects make use of a distributed version control system (e.g., git).
7. **Coding Style**: Projects must adopt the basic style recommendations of [PEP 8](https://www.python.org/dev/peps/pep-0008/) and static analysis tools should be used to identify deviations from the basic style recommendations (e.g. pylint, flake8, pycodestyle).
8. **Documentation**: All functions, classes, and modules must have documentation strings (docstrings) provided in a standard [conventions](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
9. **Testing**: Stable packages must provide unit tests of individual components (e.g. functions, classes) as well as integration tests that test the interaction between components that covers most of the code. Testing coverage should be measured. Automated testing is recommended, in which tests are run before any code is merged. System[link] and acceptance[link] testing are also recommended.
8. **Documentation**: All functions, classes, and modules in the public-facing application programming interface (API) must have documentation strings (docstrings) provided in a standard [convention](https://www.python.org/dev/peps/pep-0257/) (e.g. [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html)). Functions, classes, and modules that are not public-facing should generally have docstring to enable developers to maintain them. Docstrings must describe the code’s purpose, describe all inputs and outputs, and provide examples. High level documentation must also be provided as guides, tutorials, and developer docs. Documentation must be provided in version control with the code and be made available online in a readable form.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"should generally have docstring" --should be plural.

15. **Code of conduct**: Each project must adopt a code of conduct that is compatible with the [Contributor Covenant](https://www.contributor-covenant.org) and make it publicly available.

11. **Python 3**: All packages must be compatible with Python 3. Providing ongoing support for Python 2 is not recommended as the end of life for Python 2 was January 1, 2020 (see [PEP 373](https://www.python.org/dev/peps/pep-0373/)).
12. **Deprecation Policy** (in accordance with [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html)): Each project should support (1) all minor versions of Python released 42 months prior to the project, and at minimum the two latest minor versions; and (2) all minor versions of NumPy released in the 24 months prior to the project, and at minimum the last three minor versions. In ``setup.py``, the ``python_requires`` variable should be set to the minimum supported version of Python. All supported minor versions of Python should be in the test matrix and have binary artifacts built for the release. Minimum Python and NumPy version support should be adjusted upward only on major and minor releases, and never on a patch release.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can't this just be "projects should comply with NEP 29"?

@Cadair
Copy link

Cadair commented Feb 7, 2020

On line wrapping, I generally find the best thing is one line per sentence. It (ab)uses the git diff algorithm to highlight changes on the sentence by sentence basis.

@blalterman
Copy link
Contributor

blalterman commented Feb 7, 2020 via email

@asreimer
Copy link

asreimer commented Jun 9, 2020

The HDEE Step-2 are due 1 July. Is it expected that the PyHC standards will be updated before the due date?

standards.md Outdated Show resolved Hide resolved
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.